Version: 1.3.0

Chat API Documentation

Chat Retrieval Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/
Summary: Retrieves chat history for a specific bot with optional filtering and pagination.

Description

Retrieves chat history for a specific bot with optional filtering and pagination.

Request

Content-Type: application/json
Query Parameters
Name Description Type Constraints
chat_bot_id Chatbot identifier UUID
page_no Page number number Min: 1
page_size Number of records per page number Min: 1
order Sort order string ["asc", "desc"]
Payload
Field Description Type Constraints
text Search text in queries/responses string Optional
created_by Filter by user ID string Optional, Valid user ID

Field	Description	Type	Constraints
text	Search text in queries/responses	string	Optional
created_by	Filter by user ID	string	Optional, Valid user ID

Response

Success (200 OK)

{
  "status_code": 200,
  "message": "Chat history fetched successfully",
  "total_count": 1,
  "data": {
    "has_continuations": false,
    "chat_hist": [{
      "_id": "string",                    // MongoDB ObjectId
      "tenant_id": "string",              // UUID
      "user_id": "string",
      "object_id": "string?",
      "user_query": "string",
      "bot_response": "string",
      "chat_bot_id": "string",            // UUID
      "user_type": "internal|external",
      "is_cleared": "integer",               // 0 or 1
      "creation_time": "string",          // ISO8601
      "response_time": "string",          // ISO8601
      "metadata": {
        "category": "chat|event"
      },
      "is_positive": "boolean?",
      "query_response_id": "string",
      "chat_bot_name": "string"
    }]
  }
}

Other Responses

No Records Found Response

{
  "status_code": 404,
  "message": "No chat record found",
  "total_count": 0,
  "data": {
    "has_continuations": false,
    "chat_hist": []
  }
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "chat_bot_id": "bot-uuid-here",
    "page_no": 1,
    "page_size": 10,
    "order": "asc"
}

data = {
    "text": "search query",
    "created_by": "user123"
}

response = requests.post(url, headers=headers, params=params, json=data)

if response.status_code == 200:
    print("Chat History:", response.json())
else:
    print("Error:", response.status_code, response.text)

Chat Download Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/download/

Description

Downloads chat history as a PDF file for a specific bot. Returns a URL to access the generated PDF.

Request

Content-Type: application/json

Name	Description	Type	Constraints
chat_bot_id	Chatbot identifier	UUID
object_id	Associated object identifier	string	Max length: 100
ext_ref_user_id	External reference user ID	string	Max length: 100
text	Search text in queries/responses	string	Max length: 500
created_by	Filter by user ID	string	Valid user ID

Response

Success Response

{
  "message": "PDF uploaded to S3 successfully",
  "file_url": "https://kadal.ai/chat_history/{tenant_id}/{filename}"
}

Other Responses

{
  "status_code": 404,
  "message": "No chat record found",
  "total_count": 0,
  "data": {
    "has_continuations": false,
    "chat_hist": []
  }
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/download/"
token = "token-here"


headers = {
    "Origin": "https://kadal.ai",
    "Authorization": f"Bearer {token}"
}

query_params = {
    "chat_bot_id": "bot-uuid-here"
}

response = requests.post(url, headers=headers, params=query_params)

if response.status_code == 200:
    print("Download URL:", response.json())
else:
    print("Error:", response.status_code, response.text)

Chat Clear History Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/clearhistory

Description

Clears chat history for a specific bot with optional filtering.

Request

Content-Type: application/json

Parameters

Name	Type	Required	Description	Constraints
chat_bot_id	UUID	Yes	Chatbot identifier	Valid UUID format
object_id	string	No	Associated object identifier	Max length: 100
ext_ref_user_id	string	No	External reference user ID	Max length: 100

Response

Success Response

{
  "status_code": 200,
  "message": "Previous conversations deleted successfully",
  "query_response_id": null,
  "finish_reason": ""
}

Other Responses

{
  "status_code": 404,
  "message": "Agent wasn't found.",
  "query_response_id": "",
  "finish_reason": "no_bot_found"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/clearhistory"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "chat_bot_id": "bot-uuid-here",
    "object_id": "obj123",
    "ext_ref_user_id": "user123"
}

response = requests.post(url, headers=headers, params=params)

if response.status_code == 200:
    print("History cleared:", response.json())
else:
    print("Error:", response.status_code, response.text)

Stream Chat Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/{chat_bot_id}/stream

Description

Streams chat responses with support for file handling and tool configurations.

Request

Content-Type: application/json
Path Parameter
Name Description Type Constraints Required
chat_bot_id Chatbot identifier UUID - Yes

Name	Description	Type	Constraints	Required
chat_bot_id	Chatbot identifier	UUID	-	Yes

Query Parameter

Name	Description	Type	Constraints	Required
stream	Enable token-by-token streaming	boolean	Default: false	No
continue_last_chat	Continue previous context	boolean	Default: false	No
object_id	Associated object identifier	string	Default: null	No

Payload

{
  "message": "string",
  "is_tool_calling": false,
  "metadata": {
    "category": "chat"  // See metadata types below
  }
}

Metadata Types

Basic Chat

{
  "category": "chat"
}

File Processing

{
  "category": "event",
  "type": "file",
  "files": [{
    "file_name": "string",
    "file_type": "string",
    "object_id": "string?",
    "folder_id": "string?",
    "source_category": "InputFile|ContextFile|KnowledgeBase|Guideline|OutputTemplate",
    "input_type": "Repository|Computer|GDrive"
  }]
}

Tool Configuration

{
  "category": "event",
  "type": "tool",
  "message": "string",
  "tool_config": {
    "web_search": "boolean",
    "content_lake": "boolean"
  }
}

Model Switch

  "metadata": {
    "category": "event",
    "type": "verbose",
    "message": "string",
    "modelId" : "string",
    "modelVersion": "string"
}

Response

Non-streaming Response (application/x-ndjson)

{"status_code":200,"message":"Response message","session_id":null,"query_response_id":"68ac044e3b3b0e000a5a7dc8","finish_reason":"stop"}

Streaming Response (application/x-ndjson)

{"status_code":200,"message":"The","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" phrase","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" \"","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"Mary","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" had","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" a","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" little","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" lamb","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"\"","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" contains","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" ","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"5","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" words","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":".","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"#","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"stop"}

Other Responses

{
  "status_code": 200,
  "message": "The context is too lengthy for effective processing. Please revise your templates, guidelines, or instructions to make them more concise, or upload a smaller file.",
  "finish_reason": "input_exceeded_context_window"
}

Safety Guardrail Hit

{
  "status_code": 200,
  "message": "Sorry, the model cannot answer this question due to harmful or sensitive information. This will be recorded as a violation, and your administrator will be notified.",
  "finish_reason": "guardrail_hit"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/{chat_bot_id}/stream"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "stream": True,
    "continue_last_chat": False
}

data = {
    "message": "Hello",
    "is_tool_calling": False,
    "metadata": {
        "category": "chat"
    }
}

response = requests.post(url, headers=headers, params=params, json=data, stream=True)

for line in response.iter_lines():
    if line:
        print(line.decode())

Chat Feedback Endpoint

Description

Submits feedback for chat interactions with optional metadata and details.

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v3/feedbacks

Request

Content-Type: application/json

Payload

Name	Description	Type	Constraints	Required
chatbotId	Bot identifier	string	UUID format	No
consumerId	Consumer ID	integer	-	No
keycloakConsumerId	Keycloak consumer ID	string	UUID format	No
tenantId	Tenant ID	integer	-	No
keycloakTenantId	Keycloak tenant ID	string	UUID format	No
reason	Feedback reason	string	One of ["pre-defined", "other"]	No
details	Detailed feedback	string	Max length: 1000	No
user_query_id	Query ID	integer	-	No
query	Original user query	string	Max length: 500	No
metadata	Additional metadata	object	-	No

{
  "chatbotId": "string?",              // UUID format
  "consumerId": "number?",             // Integer
  "keycloakConsumerId": "string?",     // UUID format
  "tenantId": "number?",               // Integer
  "keycloakTenantId": "string?",       // UUID format
  "reason": "string?",                 // Pre-defined or custom
  "details": "string?",                // Detailed feedback
  "user_query_id": "number?",          // Integer
  "query": "string?",                  // Original user query
  "metadata": {                        // Optional metadata
    "source": "string?",
    "version": "string?"
  }
}

Response

Success Response

{
  "status": "success",
  "message": "Feedback submitted successfully",
  "document_id": "67eba353969855dc98a85e37"
}

Other Responses

{
  "status_code": 400,
  "message": "Invalid request format",
  "error": "VALIDATION_ERROR"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v3/feedbacks"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "chatbotId": "550e8400-e29b-41d4-a716-446655440000",
    "consumerId": 8,
    "reason": "pre-defined",
    "details": "Not factually correct",
    "query": "What are the main features?",
    "metadata": {
        "source": "web",
        "version": "1.0.2"
    }
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 201:
    print("Feedback submitted:", response.json())
else:
    print("Error:", response.status_code, response.text)

Name	Description	Type	Constraints
chat_bot_id	Chatbot identifier	UUID
page_no	Page number	number	Min: 1
page_size	Number of records per page	number	Min: 1
order	Sort order	string	["asc", "desc"]

Chat API Documentation

Chat Retrieval Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Success (200 OK)​

Other Responses​

No Records Found Response​

Usage​

Chat Download Endpoint​

Description​

Request​

Response​

Success Response​

Other Responses​

Usage​

Chat Clear History Endpoint​

Description​

Request​

Parameters​

Response​

Success Response​

Other Responses​

Usage​

Stream Chat Endpoint​

Description​

Request​

Path Parameter​

Query Parameter​

Payload​

Metadata Types​

Response​

Non-streaming Response (application/x-ndjson)​

Streaming Response (application/x-ndjson)​

Other Responses​

Safety Guardrail Hit​

Usage​

Chat Feedback Endpoint​

Description​

Request​

Payload​

Response​

Success Response​

Other Responses​

Usage​

Chat Retrieval Endpoint

Description

Request

Query Parameters

Payload

Response

Success (200 OK)

Other Responses

No Records Found Response

Usage

Chat Download Endpoint

Description

Request

Response

Success Response

Other Responses

Usage

Chat Clear History Endpoint

Description

Request

Parameters

Response

Success Response

Other Responses

Usage

Stream Chat Endpoint

Description

Request

Path Parameter

Query Parameter

Payload

Metadata Types

Response

Non-streaming Response (application/x-ndjson)

Streaming Response (application/x-ndjson)

Other Responses

Safety Guardrail Hit

Usage

Chat Feedback Endpoint

Description

Request

Payload

Response

Success Response

Other Responses

Usage